Eclipse Platform
Pre-release 3.0

org.eclipse.core.runtime.jobs
Interface IJobManager


public interface IJobManager

The job manager provides facilities for scheduling, querying, and maintaining jobs and locks. In particular, the job manager provides the following services:

This interface is not intended to be implemented by clients.

Since:
3.0
See Also:
Job, ILock

Method Summary
 void addJobChangeListener(IJobChangeListener listener)
          Registers a job listener with the job manager.
 void beginRule(ISchedulingRule rule, IProgressMonitor monitor)
          Begins applying this rule in the calling thread.
 void cancel(Object family)
          Cancels all jobs in the given job family.
 Job currentJob()
          Returns the job that is currently running in this thread, or null if there is no currently running job.
 void endRule(ISchedulingRule rule)
          Ends the application of a rule to the calling thread.
 Job[] find(Object family)
          Returns all waiting, executing and sleeping jobs belonging to the given family.
 void join(Object family, IProgressMonitor monitor)
          Waits until all jobs of the given family are finished.
 ILock newLock()
          Creates a new lock object.
 void removeJobChangeListener(IJobChangeListener listener)
          Removes a job listener from the job manager.
 void setLockListener(LockListener listener)
          Provides a hook that is notified whenever a thread is about to wait on a lock, or when a thread is about to release a lock.
 void setProgressProvider(ProgressProvider provider)
          Registers a progress provider with the job manager.
 void shutdown()
          Shuts down the job manager.
 void sleep(Object family)
          Requests that all jobs in the given job family be suspended.
 void startup()
          Starts up the job manager.
 void wakeUp(Object family)
          Resumes scheduling of all sleeping jobs in the given family.
 

Method Detail

addJobChangeListener

public void addJobChangeListener(IJobChangeListener listener)
Registers a job listener with the job manager. Has no effect if an identical listener is already registered.

Parameters:
listener - the listener to be added.

beginRule

public void beginRule(ISchedulingRule rule,
                      IProgressMonitor monitor)
Begins applying this rule in the calling thread. If the rule conficts with another rule currently running in another thread, this method blocks until there are no conflicting rules. Calls to beginRule must eventually be followed by a matching call to endRule in the same thread and with the identical rule instance.

Rules can be nested only if the rule for the inner beginRule is contained within the rule for the outer beginRule. Rule containment is tested with the API method ISchedulingRule.contains. Also, begin/end pairs must be strictly nested. Only the rule that has most recently begun can be ended at any given time.

A rule of null can be used, but will be ignored for scheduling purposes. The outermost non-null rule in the thread will be used for scheduling. A null rule that is begun must still be ended.

If this method is called from within a job that has a scheduling rule, the given rule must also be contained within the rule for the running job.

Note that endRule must be called even if beginRule fails. The recommended usage is:

 final ISchedulingRule rule = ...;
 try {
 	manager.beginRule(rule, monitor);
 } finally {
 	manager.endRule(rule);
 }
 

This API is experimental, and is subject to change or removal without notice.

Parameters:
rule - the rule to begin applying in this thread, or null
monitor - a progress monitor, or null if progress reporting and cancellation are not desired
Throws:
IllegalArgumentException - if the rule is not strictly nested within all other rules currently active for this thread.
OperationCanceledException - if the supplied monitor reports cancelation before the rule becomes available.
See Also:
ISchedulingRule.contains

cancel

public void cancel(Object family)
Cancels all jobs in the given job family. Jobs in the family that are currently waiting will be removed from the queue. Sleeping jobs will be discarded without having a chance to wake up. Currently executing jobs will be asked to cancel but there is no guarantee that they will do so.

Parameters:
family - the job family to cancel, or null to cancel all jobs.
See Also:
Job.belongsTo(Object)

currentJob

public Job currentJob()
Returns the job that is currently running in this thread, or null if there is no currently running job.


endRule

public void endRule(ISchedulingRule rule)
Ends the application of a rule to the calling thread. Calls to endRule must be preceded by a matching call to beginRule in the same thread with an identical rule instance.

Rules can be nested only if the rule for the inner beginRule is contained within the rule for the outer beginRule. Also, begin/end pairs must be strictly nested. Only the rule that has most recently begun can be ended at any given time.

This API is experimental, and is subject to change or removal without notice.

Parameters:
rule - the rule to end applying in this thread
Throws:
IllegalArgumentException - if this method is called on a rule for which there is no matching begin, or that does not match the most recent begin.
See Also:
ISchedulingRule.contains(org.eclipse.core.runtime.jobs.ISchedulingRule)

find

public Job[] find(Object family)
Returns all waiting, executing and sleeping jobs belonging to the given family. If no jobs are found, an empty array is returned.

Parameters:
family - the job family to find, or null to find all jobs.
See Also:
Job.belongsTo(Object)

join

public void join(Object family,
                 IProgressMonitor monitor)
          throws InterruptedException,
                 OperationCanceledException
Waits until all jobs of the given family are finished. This method will block the calling thread until all such jobs have finished executing, or until this thread is interrupted. If there are no jobs in the family that are currently waiting, running, or sleeping, this method returns immediately. Feedback on how the join is progressing is provided to a progress monitor.

If the calling thread owns any locks, the locks may be released during the join if necessary to prevent deadlock. On return from the join, the calling thread will once again have exclusive control of any locks that were owned upon entering the join.

Warning: this method can result in starvation of the current thread if another thread continues to add jobs of the given family.

Parameters:
family - the job family to join, or null to join all jobs.
monitor - Progress monitor for reporting progress on how the wait is progressing, or null if no progress monitoring is required.
Throws:
InterruptedException - if this thread is interrupted while waiting
OperationCanceledException - if the progress monitor is canceled while waiting
See Also:
Job.belongsTo(Object)

newLock

public ILock newLock()
Creates a new lock object. All lock objects supplied by the job manager know about each other and will always avoid circular deadlock amongst themselves.

Returns:
the new lock object

removeJobChangeListener

public void removeJobChangeListener(IJobChangeListener listener)
Removes a job listener from the job manager. Has no effect if an identical listener is not already registered.

Parameters:
listener - the listener to be removed.

setLockListener

public void setLockListener(LockListener listener)
Provides a hook that is notified whenever a thread is about to wait on a lock, or when a thread is about to release a lock. This hook must only be set once.

This method is for internal use by the platform-related plug-ins. Clients should not call this method.

See Also:
LockListener

setProgressProvider

public void setProgressProvider(ProgressProvider provider)
Registers a progress provider with the job manager. If there was a provider already registered, it is replaced.

This method is for internal use by the platform-related plug-ins. Clients should not call this method.

Parameters:
provider - the new provider, or null if no progress is needed.

shutdown

public void shutdown()
Shuts down the job manager. Scheduled jobs in the WAITING or SLEEPING states will be canceled. Jobs in the RUNNING state will be told to stop, but there is no guarantee that they will do so. If the job manager is already shut down, this method has no effect.

After shutdown, no new jobs can be scheduled with the job manager until startup is called on it.

Since this method will cause pending work to be canceled, it must only be called by the application when it is shutting down. It is not intended to be called by other plugins.

See Also:
startup()

sleep

public void sleep(Object family)
Requests that all jobs in the given job family be suspended. Jobs currently waiting to be run will be removed from the queue and moved into the SLEEPING state. Jobs that have been put to sleep will remain in that state until either resumed or canceled. This method has no effect on jobs that are not currently waiting to be run. Sleeping jobs can be resumed using wakeUp.

Parameters:
family - the job family to sleep, or null to sleep all jobs.
See Also:
Job.belongsTo(Object)

startup

public void startup()
Starts up the job manager. New jobs can now be scheduled to run with the job manager. If the job manager is already started, this method has no effect.

By default, the job manager's lifecycle is tied to the platform. It is started when the platform starts up, and is shutdown before the platform exits. If plugins choose to shutdown the job manager while the platform is running, it must be restarted using this method before new jobs can be scheduled.

See Also:
shutdown

wakeUp

public void wakeUp(Object family)
Resumes scheduling of all sleeping jobs in the given family. This method has no effect on jobs in the family that are not currently sleeping.

Parameters:
family - the job family to wake up, or null to wake up all jobs.
See Also:
Job.belongsTo(Object)

Eclipse Platform
Pre-release 3.0

Copyright (c) IBM Corp. and others 2000, 2003. All Rights Reserved.